<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>Aria: threadExample.cpp</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Aria
   &#160;<span id="projectnumber">2.9.1</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li><a href="examples.html"><span>Examples</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('threadExample_8cpp-example.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">threadExample.cpp</div>  </div>
</div><!--header-->
<div class="contents">
<p>Example showing ARIA's cross-platform threading tools.ARIA provides some tools for writing multithreaded programs. These are abstractions of the threading library provided by the native operating system.</p>
<p>The three main tools are: </p><ul>
<li>
<a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a> a class which can run a method in a new thread </li>
<li>
<a class="el" href="classArMutex.html" title="Cross-platform mutex wrapper class. ">ArMutex</a>, an object that can be shared by multiple threads to provide mutual exclusion from other shared data. </li>
<li>
<a class="el" href="classArCondition.html" title="Threading condition wrapper class. ">ArCondition</a>, an object that can cause a thread to block execution until signaled by another thread to continue. </li>
</ul>
<p>This example program shows the use of all three, with two threads interacting: the program's main thread of execution, and a new thread created using <a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a>. An <a class="el" href="classArMutex.html" title="Cross-platform mutex wrapper class. ">ArMutex</a> object is used to keep use of some shared data safe, and then the use of <a class="el" href="classArCondition.html" title="Threading condition wrapper class. ">ArCondition</a> is shown.</p>
<p>Threading can be error-prone, since any (perhaps subconcious) assumptions you have about the linear execution of code may not apply to simultaneous threads. Furthermore, different computers will execute multithreaded code in different ways (especially if they have different numbers of CPUs). ARIA's threading tools can help make multiple threads work, and help make multithreaded code portable, but you must always think carefully about how code might execute (including error conditions!) to avoid deadlocks and race conditions.</p>
<div class="fragment"><div class="line"></div><div class="line"><span class="preprocessor">#include &quot;Aria.h&quot;</span></div><div class="line"></div><div class="line"></div><div class="line"><span class="comment">/* A subclass of ArASyncTask, to contain a method that runs in a new thread */</span></div><div class="line"><span class="keyword">class </span>ExampleThread : <span class="keyword">public</span> <a name="_a0"></a><a class="code" href="classArASyncTask.html">ArASyncTask</a></div><div class="line">{</div><div class="line">  <a name="_a1"></a><a class="code" href="classArCondition.html">ArCondition</a> myCondition;</div><div class="line">  <a name="_a2"></a><a class="code" href="classArMutex.html">ArMutex</a> myMutex;</div><div class="line">  <span class="keywordtype">int</span> myCounter;</div><div class="line"><span class="keyword">public</span>:</div><div class="line"></div><div class="line">  <span class="comment">/* Construtor. Initialize counter. */</span></div><div class="line">  ExampleThread() : myCounter(0)</div><div class="line">  {</div><div class="line">    myCondition.<a name="a3"></a>setLogName(<span class="stringliteral">&quot;ExampleThreadCondition&quot;</span>);</div><div class="line">  }</div><div class="line"></div><div class="line"></div><div class="line">  <span class="comment">/* This method is called in the new thread when launched. The void* parameter</span></div><div class="line"><span class="comment">   * and return value are platform implementation-specific and can be ignored.</span></div><div class="line"><span class="comment">   * This method will run in a loop, incrementing the counter each second, but </span></div><div class="line"><span class="comment">   * locking the mutex to prevent conflicting access by other threads. </span></div><div class="line"><span class="comment">   * If it reaches a value divisible by ten, signal our condition variable.</span></div><div class="line"><span class="comment">   */</span></div><div class="line">  <span class="keywordtype">void</span>* <a name="a4"></a><a class="code" href="classArASyncTask.html#a370bd38ad2a285af30cf722a9e3f4532">runThread</a>(<span class="keywordtype">void</span>*) </div><div class="line">  {</div><div class="line">    <span class="comment">// Run until the thread is requested to end by another thread.</span></div><div class="line">    <span class="keywordflow">while</span>(this-&gt;<a name="a5"></a><a class="code" href="classArThread.html#a05333f5f05022f42ab46a6dd8a8f1958">getRunningWithLock</a>())</div><div class="line">    {</div><div class="line">      myMutex.<a name="a6"></a><a class="code" href="classArMutex.html#a7b6aee74872c19fb8829d96dc3e52f34">lock</a>();</div><div class="line"></div><div class="line">      <span class="comment">// Increment the counter. </span></div><div class="line">      myCounter++;</div><div class="line">      <a name="a7"></a><a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a name="a8"></a><a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a7040faf60eeb155eaa85d439b1066ca1">ArLog::Normal</a>, <span class="stringliteral">&quot;Example thread: incremented counter to %d.&quot;</span>, myCounter);</div><div class="line"></div><div class="line">      <span class="comment">// If it&#39;s now divisible by 10, signal the condition variable.</span></div><div class="line">      <span class="keywordflow">if</span>(myCounter % 10 == 0)</div><div class="line">      {</div><div class="line">        <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a7040faf60eeb155eaa85d439b1066ca1">ArLog::Normal</a>, <span class="stringliteral">&quot;Example thread: Signalling condition.&quot;</span>);</div><div class="line">        myCondition.<a name="a9"></a><a class="code" href="classArCondition.html#a6c00c69e916c722cdce96d819a354b37">signal</a>();</div><div class="line">      }</div><div class="line"></div><div class="line">      <span class="comment">// Unlock, then sleep.  We unlock before the sleep, so that while</span></div><div class="line">      <span class="comment">// we are sleeping, other threads that try to lock the mutex won&#39;t</span></div><div class="line">      <span class="comment">// be blocked until this thread is done sleeping.</span></div><div class="line">      myMutex.<a name="a10"></a><a class="code" href="classArMutex.html#afb51b5514a9456f23441e479fe58fb46">unlock</a>();</div><div class="line">      <a name="a11"></a><a class="code" href="group__easy.html#ga4dfb878a3f9123b8dd96ae05b2fd94cb">ArUtil::sleep</a>(1000);</div><div class="line">    }</div><div class="line"></div><div class="line">    <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a7040faf60eeb155eaa85d439b1066ca1">ArLog::Normal</a>, <span class="stringliteral">&quot;Example thread: requested stop running, ending thread.&quot;</span>);</div><div class="line">    <span class="keywordflow">return</span> NULL;</div><div class="line">  }</div><div class="line"></div><div class="line">  <span class="comment">/* Other threads can call this to wait for a condition eventually</span></div><div class="line"><span class="comment">   * signalled by this thread. (So note that in this example program, this </span></div><div class="line"><span class="comment">   * function is not executed within &quot;Example thread&quot;, but is executed in the main thread.)</span></div><div class="line"><span class="comment">   */</span></div><div class="line">  <span class="keywordtype">void</span> waitOnCondition()</div><div class="line">  {</div><div class="line">    myCondition.<a name="a12"></a><a class="code" href="classArCondition.html#af2b4daa37ab40fad88caee7c9c3075ef">wait</a>();</div><div class="line">    <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a7040faf60eeb155eaa85d439b1066ca1">ArLog::Normal</a>, <span class="stringliteral">&quot; %s ArCondition object was signalled, done waiting for it.&quot;</span>, myCondition.<a name="a13"></a>getLogName()); </div><div class="line">  }</div><div class="line"></div><div class="line">  <span class="comment">/* Get the counter. Not threadsafe, you must lock the mutex during access. */</span></div><div class="line">  <span class="keywordtype">int</span> getCounter() { <span class="keywordflow">return</span> myCounter; }</div><div class="line"></div><div class="line">  <span class="comment">/* Set the countner. Not threadsafe, you must lock the mutex during access. */</span></div><div class="line">  <span class="keywordtype">void</span> setCounter(<span class="keywordtype">int</span> ctr) { myCounter = ctr; }</div><div class="line"></div><div class="line">  <span class="comment">/* Lock the mutex object.  */</span></div><div class="line">  <span class="keywordtype">void</span> lockMutex() { myMutex.<a class="code" href="classArMutex.html#a7b6aee74872c19fb8829d96dc3e52f34">lock</a>(); }</div><div class="line"></div><div class="line">  <span class="comment">/* Unlock the mutex object. */</span></div><div class="line">  <span class="keywordtype">void</span> unlockMutex() { myMutex.<a class="code" href="classArMutex.html#afb51b5514a9456f23441e479fe58fb46">unlock</a>(); }</div><div class="line"></div><div class="line">};</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">  <a name="a14"></a><a class="code" href="classAria.html#ad99c16b5d947229d9f8e1c5b2d4cdd73">Aria::init</a>();</div><div class="line"></div><div class="line">  ExampleThread exampleThread;</div><div class="line"></div><div class="line">  <span class="comment">/* Launch the new thread in the background. This thread (i.e. the main program thread, </span></div><div class="line"><span class="comment">   * executing main()) continues immediately after the new thread is created. */</span></div><div class="line">  <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a7040faf60eeb155eaa85d439b1066ca1">ArLog::Normal</a>, <span class="stringliteral">&quot;Main thread: Running new example thread ...&quot;</span>);</div><div class="line">  exampleThread.runAsync();</div><div class="line"></div><div class="line">  <span class="comment">/* Loop, reading the value contained in the ExampleThread object.</span></div><div class="line"><span class="comment">   * We will also use ArUtil::sleep() to make this thread sleep each iteration,</span></div><div class="line"><span class="comment">   * instead of running as fast as possible and potentially preventing other</span></div><div class="line"><span class="comment">   * threads from access to the mutex and the shared counter.</span></div><div class="line"><span class="comment">   * When the counter reaches 10, break out of the loop and then wait on the</span></div><div class="line"><span class="comment">   * condition variable.</span></div><div class="line"><span class="comment">   */</span></div><div class="line">  <span class="keywordflow">while</span>(<span class="keyword">true</span>)</div><div class="line">  {</div><div class="line">    exampleThread.lockMutex();</div><div class="line">    <span class="keywordtype">int</span> c = exampleThread.getCounter();</div><div class="line">    exampleThread.unlockMutex(); <span class="comment">// we can unlock the mutex now, since we made a copy of the counter.</span></div><div class="line"></div><div class="line">    printf(<span class="stringliteral">&quot;Main thread: Counter=%d.\n&quot;</span>, c);</div><div class="line"></div><div class="line">    <span class="keywordflow">if</span>(c &gt;= 10)</div><div class="line">      <span class="keywordflow">break</span>;</div><div class="line"></div><div class="line">    <a class="code" href="group__easy.html#ga4dfb878a3f9123b8dd96ae05b2fd94cb">ArUtil::sleep</a>(600);</div><div class="line">  }</div><div class="line"></div><div class="line"></div><div class="line">  <span class="comment">/* This shows how to block on an ArCondition object. </span></div><div class="line"><span class="comment">   * wait() will *only* return when the condition object is </span></div><div class="line"><span class="comment">   * signaled by the other thread.</span></div><div class="line"><span class="comment">   */</span></div><div class="line">  <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a7040faf60eeb155eaa85d439b1066ca1">ArLog::Normal</a>, <span class="stringliteral">&quot;Main thread: Waiting on condition object...&quot;</span>);</div><div class="line">  exampleThread.waitOnCondition();</div><div class="line"></div><div class="line">  <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a7040faf60eeb155eaa85d439b1066ca1">ArLog::Normal</a>, <span class="stringliteral">&quot;Main thread: Condition was signaled, and execution continued. Telling the other thread to stop running.&quot;</span>);</div><div class="line">  exampleThread.stopRunning();</div><div class="line">  </div><div class="line">  <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a7040faf60eeb155eaa85d439b1066ca1">ArLog::Normal</a>, <span class="stringliteral">&quot;Main thread: Waiting for the other thread to exit, then exiting the program.&quot;</span>);</div><div class="line">  <span class="keywordflow">do</span> {</div><div class="line">    <a class="code" href="group__easy.html#ga4dfb878a3f9123b8dd96ae05b2fd94cb">ArUtil::sleep</a>(250);</div><div class="line">  } <span class="keywordflow">while</span>(exampleThread.getRunningWithLock());</div><div class="line"></div><div class="line">  <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a7040faf60eeb155eaa85d439b1066ca1">ArLog::Normal</a>, <span class="stringliteral">&quot;Main thread: Exiting program.&quot;</span>);</div><div class="line">  <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --> </div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.11 </li>
  </ul>
</div>
</body>
</html>
